/*
 * This software code is (c) 2010 T-Mobile USA, Inc. All Rights Reserved.
 *
 * Unauthorized redistribution or further use of this material is
 * prohibited without the express permission of T-Mobile USA, Inc. and
 * will be prosecuted to the fullest extent of the law.
 *
 * Removal or modification of these Terms and Conditions from the source
 * or binary code of this software is prohibited.  In the event that
 * redistribution of the source or binary code for this software is
 * approved by T-Mobile USA, Inc., these Terms and Conditions and the
 * above copyright notice must be reproduced in their entirety and in all
 * circumstances.
 *
 * No name or trademarks of T-Mobile USA, Inc., or of its parent company,
 * Deutsche Telekom AG or any Deutsche Telekom or T-Mobile entity, may be
 * used to endorse or promote products derived from this software without
 * specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" AND "WITH ALL FAULTS" BASIS
 * AND WITHOUT WARRANTIES OF ANY KIND.  ALL EXPRESS OR IMPLIED
 * CONDITIONS, REPRESENTATIONS OR WARRANTIES, INCLUDING ANY IMPLIED
 * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
 * NON-INFRINGEMENT CONCERNING THIS SOFTWARE, ITS SOURCE OR BINARY CODE
 * OR ANY DERIVATIVES THEREOF ARE HEREBY EXCLUDED.  T-MOBILE USA, INC.
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE
 * OR ITS DERIVATIVES.  IN NO EVENT WILL T-MOBILE USA, INC. OR ITS
 * LICENSORS BE LIABLE FOR LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
 * INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
 * HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT
 * OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF T-MOBILE USA,
 * INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 *
 * THESE TERMS AND CONDITIONS APPLY SOLELY AND EXCLUSIVELY TO THE USE,
 * MODIFICATION OR DISTRIBUTION OF THIS SOFTWARE, ITS SOURCE OR BINARY
 * CODE OR ANY DERIVATIVES THEREOF, AND ARE SEPARATE FROM ANY WRITTEN
 * WARRANTY THAT MAY BE PROVIDED WITH A DEVICE YOU PURCHASE FROM T-MOBILE
 * USA, INC., AND TO THE EXTENT PERMITTED BY LAW.
 */

package javax.microedition.ims.presence;

/**
 * Helper interface to describe the type of event that caused the current state
 * of a specific subscription. For example, the application can be notified of
 * why a subscription was terminated.
 * </p><p>For detailed implementation guidelines and for complete API docs,
 * please refer to JSR-281 and JSR-235 documentation.
 * 
 * @author Andrei Khomushko
 * 
 */
public interface Event {

    /**
     * Identifier for the event approved. Indicates that the subscription has
     * been approved.
     */
    int EVENT_APPROVED = 2;

    /**
     * Identifier for the event deactivated. According to [RFC3265], the
     * subscription has been terminated, but the client SHOULD retry immediately
     * with a new subscription. The "retry-after" parameter has no semantics for
     * this event.
     */
    int EVENT_DEACTIVATED = 3;

    /**
     * Identifier for the event giveup. According to [RFC3265], the subscription
     * has been terminated because the notifier could not obtain authorization
     * in a timely fashion. If a "retry-after" parameter is also present, the
     * client SHOULD wait at least the number of seconds specified by that
     * parameter before attempting to re-subscribe; otherwise, the client MAY
     * retry immediately, but will likely get put back into pending state.
     */
    int EVENT_GIVEUP = 7;

    /**
     * Identifier for the event noresource. According to [RFC3265], the
     * subscription has been terminated because the resource state which was
     * being monitored no longer exists. Clients SHOULD NOT attempt to
     * re-subscribe. The "retry-after" parameter has no semantics for this event.
     */
    int EVENT_NORESOURCE = 8;

    /**
     * Identifier for the event probation. According to [RFC3265], the
     * subscription has been terminated, but the client SHOULD retry at some
     * later time. If a "retry-after" parameter is also present, the client
     * SHOULD wait at least the number of seconds specified by that parameter
     * before attempting to re-subscribe.
     */
    int EVENT_PROBATION = 4;

    /**
     * Identifier for the event rejected. According to [RFC3265], the
     * subscription has been terminated due to change in authorization policy.
     * Clients SHOULD NOT attempt to re-subscribe. The "retry-after" parameter
     * has no semantics for this event.
     */
    int EVENT_REJECTED = 5;

    /**
     * Identifier for the event subscribe. Indicates that the current state of
     * the subscription was caused by a subscription request.
     */
    int EVENT_SUBSCRIBE = 1;

    /**
     * Identifier for the event timeout. According to [RFC3265], the
     * subscription has been terminated because it was not refreshed before it
     * expired. Clients MAY re-subscribe immediately. The "retry-after"
     * parameter has no semantics for this event.
     */
    int EVENT_TIMEOUT = 6;

    /**
     * Returns the event type that caused the current subscription state.
     * 
     * @return the event type
     */
    int getEventType();

    /**
     * Returns the time in seconds after which the request can be retried. This
     * is only meaningful if the event type is EVENT_PROBATION or EVENT_GIVEUP.
     * 
     * @return the time or -1 if no retry after information is available
     */
    int getRetryAfter();
}
